[Doc] Upgrade docs build system by peytondmurray · Pull Request #41115 · ray-project/ray

peytondmurray · 2023-11-14T03:09:28Z

Why are these changes needed?

This PR upgrades the build system for the docs.

Related issue number

Closes #37944.

Will contain all the changes in #39766, but will be reviewed in pieces via PRs against this branch.

Checks

I've signed off every commit(by using the -s flag, i.e., git commit -s) in this PR.
I've run scripts/format.sh to lint the changes in this PR.
I've included any doc changes needed for https://docs.ray.io/en/master/.
- I've added any new APIs to the API Reference. For example, if I added a
  method in Tune, I've added it in doc/source/tune/api/ under the
  corresponding .rst file.
I've made sure the tests are passing. Note that there might be a few flaky tests, see the recent failures at https://flakey-tests.ray.io/
Testing Strategy
- Unit tests
- Release tests
- This PR is not tested :(

peytondmurray · 2023-11-16T18:46:59Z

Todo

Move the parse_navbar_config etc. to e.g. custom_directives.py
Resolve conflicts with master

peytondmurray · 2023-11-16T21:17:43Z

According to RTD support the build is timing out (??). This takes 8m locally...troubleshooting now.

peytondmurray · 2023-11-18T01:58:24Z

Note: I had to reduce the version of watchfiles to 0.19.0 due to the premerge check. I'd argue the constraints should not be applied to the doc build requirements, as they're separate from the rest of the ray requirements.

Once click-contrib/sphinx-click#129 is merged, we can remove this dependency from the requirements-doc.txt.

angelinalg · 2023-11-20T18:12:14Z

The Ask AI button doesn't have a clear border. It should also be black in non-dark-mode. The Ask AI button is black in dark mode, so perhaps the color setting is just reversed.

The search bar changes size/flashes when you click on the side bar. (This is not a blocker, but we should polish it up if we can in a follow up if it's too big of a lift for this PR.)

Screen.Recording.2023-11-20.at.10.17.00.AM.mov

The dark mode switch has three modes. Two of them seem to be the same dark mode. Is this intentional?
We lost the Welcome to Ray page in the side bar, that links to the top level landing page. Overview also got a new child page, Learn more. I think Learn more is included in the Getting started page on master. Is there a reason this PR rearranges that?

emmyscode · 2023-11-20T18:22:02Z

Some inconsistencies on the main landing page with padding and a permanent light background for the code samples.
How does the user select the Ray version?
Footer includes Sphinx version information; do we want this?
The AskAI button has a very faint background so it doesn't look like a clickable button; missing Ray logo
In the rightmost column on pages, there's an "Edit on Github" button; is that something we want?

ci/ray_ci/doc_builder_container.py

ci/ray_ci/tests.env.Dockerfile

can-anyscale · 2023-11-21T00:21:39Z

nit: can we add a line here https://github.com/ray-project/ray/blob/master/ci/pipeline/determine_tests_to_run.py#L276 something like:

elif changed_file == ".readthedocs.yaml":
  RAY_CI_DOC_AFFECTED = 1

It will help to get CI results quicker. The entire test suite is run on this change despite this is only a doc change.

Signed-off-by: pdmurray <peynmurray@gmail.com>

can-anyscale

JoshTanke · 2023-11-28T17:42:03Z

@peytondmurray Was doc/source/ray-overview/eco-gallery.yml supposed to be deleted? Is there a new place to add integrations now?

peytondmurray · 2023-11-28T17:47:09Z

@JoshTanke Yes, it was. Those integrations were being generated from that yaml file and inserted into ray-overview/ray-libraries.rst. Rather than have the extra step, just modify ray-overview/ray-libraries.rst directly.

JoshTanke · 2023-11-28T17:49:51Z

@JoshTanke Yes, it was. Those integrations were being generated from that yaml file and inserted into ray-overview/ray-libraries.rst. Rather than have the extra step, just modify ray-overview/ray-libraries.rst directly.

makes sense, thank you for the info!

This PR upgrades the build system for the docs. Signed-off-by: pdmurray <peynmurray@gmail.com>

peytondmurray self-assigned this Nov 14, 2023

peytondmurray force-pushed the docs-build-system-upgrade branch from f6532c3 to bc9230d Compare November 16, 2023 20:36

peytondmurray mentioned this pull request Nov 18, 2023

[Doc] Fix cached toctree behavior peytondmurray/ray#12

Merged

8 tasks

peytondmurray force-pushed the docs-build-system-upgrade branch 3 times, most recently from 441f24c to 25c4160 Compare November 18, 2023 01:53

peytondmurray mentioned this pull request Nov 18, 2023

[Doc] Final cleanup peytondmurray/ray#13

Merged

8 tasks

peytondmurray force-pushed the docs-build-system-upgrade branch from 59f8fa0 to 6b07aac Compare November 20, 2023 22:12

can-anyscale reviewed Nov 20, 2023

View reviewed changes

ci/ray_ci/doc_builder_container.py Outdated Show resolved Hide resolved

ci/ray_ci/tests.env.Dockerfile Outdated Show resolved Hide resolved

peytondmurray force-pushed the docs-build-system-upgrade branch from f559c6a to e327fa2 Compare November 20, 2023 23:57

peytondmurray force-pushed the docs-build-system-upgrade branch from e327fa2 to 06bc86f Compare November 21, 2023 00:24

peytondmurray marked this pull request as ready for review November 21, 2023 03:28

peytondmurray requested review from edoakes, shrekris-anyscale and sihanwang41 as code owners November 21, 2023 03:28

peytondmurray added 12 commits November 27, 2023 13:43

[Doc] Refactor tab widgets

ffdc1ed

Signed-off-by: pdmurray <peynmurray@gmail.com>

[Doc] Miscellaneous changes

bbde3f0

Signed-off-by: pdmurray <peynmurray@gmail.com>

[Doc] Optimize sidebar nav creation to speed up build

93fe6bd

Signed-off-by: pdmurray <peynmurray@gmail.com>

[Doc] Fix cached toctree behavior

b1a0d78

Signed-off-by: pdmurray <peynmurray@gmail.com>

[Doc] Final cleanup

1c79729

Signed-off-by: pdmurray <peynmurray@gmail.com>

[Doc] Fix premerge CI job

6229276

Signed-off-by: pdmurray <peynmurray@gmail.com>

[Doc] Address final comments

f3b5245

Signed-off-by: pdmurray <peynmurray@gmail.com>

[Doc] Premerge troubleshooting

984476c

Signed-off-by: pdmurray <peynmurray@gmail.com>

[Doc] Install doc-dependencies.txt in doc_builder_container.py

3b03385

Signed-off-by: pdmurray <peynmurray@gmail.com>

[Doc] Fix tabs widgets in cluster/vms/getting-started

9a1bc99

Signed-off-by: pdmurray <peynmurray@gmail.com>

[Doc] Improved train logo style, pygments diff css; rework tune toctree

ac1f80a

Signed-off-by: pdmurray <peynmurray@gmail.com>

[Doc] Modify doc build dockerfile to install deps properly

f856709

Signed-off-by: pdmurray <peynmurray@gmail.com>

peytondmurray force-pushed the docs-build-system-upgrade branch from 72848dd to f856709 Compare November 27, 2023 21:44

[Doc] Fix merge conflicts

5fe326c

Signed-off-by: pdmurray <peynmurray@gmail.com>

can-anyscale approved these changes Nov 28, 2023

View reviewed changes

can-anyscale merged commit 8919bf0 into ray-project:master Nov 28, 2023

peytondmurray deleted the docs-build-system-upgrade branch November 28, 2023 01:15

This was referenced Nov 28, 2023

[WIP] [Docs] Docs deps upgrade #39766

Closed

[docs infra] left rail is no longer scrollable #41286

Closed

ujjawal-khare pushed a commit to ujjawal-khare-27/ray that referenced this pull request Nov 29, 2023

[Doc] Upgrade docs build system (ray-project#41115)

a31ddf4

This PR upgrades the build system for the docs. Signed-off-by: pdmurray <peynmurray@gmail.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Doc] Upgrade docs build system#41115

[Doc] Upgrade docs build system#41115
can-anyscale merged 21 commits intoray-project:masterfrom
peytondmurray:docs-build-system-upgrade

peytondmurray commented Nov 14, 2023 •

edited

Loading

Uh oh!

peytondmurray commented Nov 16, 2023 •

edited

Loading

Uh oh!

peytondmurray commented Nov 16, 2023 •

edited

Loading

Uh oh!

peytondmurray commented Nov 18, 2023 •

edited

Loading

Uh oh!

angelinalg commented Nov 20, 2023 •

edited by peytondmurray

Loading

Uh oh!

emmyscode commented Nov 20, 2023 •

edited by peytondmurray

Loading

Uh oh!

Uh oh!

Uh oh!

can-anyscale commented Nov 21, 2023

Uh oh!

can-anyscale left a comment

Uh oh!

JoshTanke commented Nov 28, 2023

Uh oh!

peytondmurray commented Nov 28, 2023

Uh oh!

JoshTanke commented Nov 28, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

14 participants

Conversation

peytondmurray commented Nov 14, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why are these changes needed?

Related issue number

Checks

Uh oh!

peytondmurray commented Nov 16, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Todo

Uh oh!

peytondmurray commented Nov 16, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

peytondmurray commented Nov 18, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

angelinalg commented Nov 20, 2023 • edited by peytondmurray Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

emmyscode commented Nov 20, 2023 • edited by peytondmurray Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

can-anyscale commented Nov 21, 2023

Uh oh!

can-anyscale left a comment

Choose a reason for hiding this comment

Uh oh!

JoshTanke commented Nov 28, 2023

Uh oh!

peytondmurray commented Nov 28, 2023

Uh oh!

JoshTanke commented Nov 28, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

14 participants

peytondmurray commented Nov 14, 2023 •

edited

Loading

peytondmurray commented Nov 16, 2023 •

edited

Loading

peytondmurray commented Nov 16, 2023 •

edited

Loading

peytondmurray commented Nov 18, 2023 •

edited

Loading

angelinalg commented Nov 20, 2023 •

edited by peytondmurray

Loading

emmyscode commented Nov 20, 2023 •

edited by peytondmurray

Loading